For this workshop

Presenters: Maurits Evers, Sebastian Kurscheid
Slides: https://github.com/mevers/workshop_RMarkdown

What you should bring / have brought

1. A laptop with a recent RStudio release already installed
2. A set of questions
3. (Optional) A sample text document for you to layout in RMarkdown

What you should be familiar with

1. Basic R skills: Know what a dataframe is; how to produce a plot; how to inspect an element, …
2. Basic Unix/Linux skills

Important R packages

pkg <- c("ggplot2", "rmarkdown", "knitr", "dplyr", "hrbrthemes", "scatterD3");
lapply(pkg, function(x) { if (!require(x, character.only = TRUE, quietly = TRUE)) {
  install.packages(x);
  require(x, quietly = TRUE)}
})

Example data

We will use the starwars dataset from dplyr.

head(starwars, n = 3);

## # A tibble: 3 x 13
##             name height  mass hair_color  skin_color eye_color birth_year
##            <chr>  <int> <dbl>      <chr>       <chr>     <chr>      <dbl>
## 1 Luke Skywalker    172    77      blond        fair      blue         19
## 2          C-3PO    167    75       <NA>        gold    yellow        112
## 3          R2-D2     96    32       <NA> white, blue       red         33
## # ... with 6 more variables: gender <chr>, homeworld <chr>, species <chr>,
## #   films <list>, vehicles <list>, starships <list>

Create new RMarkdown (Rmd) document in RStudio

1. File \(\rightarrow\) New File \(\rightarrow\) R Markdown

2. Specify output option

   

3. Render

0. If you need help with setting up RStudio and the necessary packages, this is the time…

1. Create a new R Markdown (Rmd) document in RStudio.
2. Select PDF, HTML and Word as output option.
3. Render the RMarkdown document to the corresponding output formats.
4. Locate and open the final output file.
5. Change the output format of an existing RMarkdown document

Document conversion

1. Rmd \(\rightarrow\) PDF, HTML, Word uses rmarkdown::render() (note that knitr::pandoc() is deprecated)
2. rmarkdown::render() uses the universal document converter pandoc (installed as part of RStudio)

For example, pandoc will translate

# Header

into the following output-specific lines:

1. For HTML output

   <h1>Header</h1>

2. For \(\LaTeX\) output

   \section{Header}

Beware the different Markdown flavours: GitHub, R Markdown, vanilla Markdown, …

Here: Focus on RMarkdown, and the following elements

1. Headers
2. Emphasis: bold and italics
3. Lists: Ordered and unordered
4. Images and links
5. Blockquotes
6. Rules and line breaks

More details:

• Markdown basics
• R Markdown Cheat Sheet
• Markdown Cheat Sheet

1. Experiment with different markdown elements in your RMarkdown document
2. Render the document and check the resulting output file
3. Are there any specific text elements you would like to typeset?

You can use language-specific expressions in RMarkdown documents.

For example:

1. In HTML documents, you can use
   • <img src="path/to/image.png" style="width:200px;"> to place an image,
   • <hr> to place a horizontal rule,
   • <ol start="10"><li>...</ol> to create an ordered list,
   • most HTML code tags.
2. In PDF documents, you can use
   • \includegraphics[width=\textwidth]{...} to place an image,
   • \begin{minipage}{.5\textwidth}...\end{minipage} to fine-tune horizontal and vertical text/figure layout,
   • a lot of the \(\LaTeX\) syntax.

Beware: A HTML statement won't be recognised if you render your RMarkdown file as a Word document.

1. Uniquely name your code chunks (replace double with single curly brackets)

    ```{{r chunk_name, ...}}

   • increases readibility
   • helps with caching
2. Whitespace is important:
   • Two whitespaces at the end of a line identify a manual linebreak
   • A list requires a preceding newline (this is not the case in e.g. GitHub-flavoured markdown)

3. Don't dev.off(): Devices are handled internally!

More Markdown-generic details:
Markdown style guide

---
title: "Main title"
subtitle: "Subtitle"
author: "Firstname Lastname"
date: "07/08/2017"
output:
  word_document
---

Main keys

1. Title and subtitle
2. Author (can have multiple authors as list for key author)
3. Date (can be R code, e.g. format(Sys.time(), '%d %B %Y'))
4. Output option: html_document, pdf_document, word_document, ioslides_presentation, beamer_presentation

1. Make changes to the existing YAML header keys title and author.
2. Change the date to automatically give the current "DayOfTheWeek, Day MonthName YearWithCentury".
3. Add a subtitle to your document.
4. Add a second authors.
5. Change the output from a Word document to a ioslides presentation.

Hint:

# R code
?strptime

Some useful options

• eval=FALSE: Don't run code.
• include=FALSE: Run code but don't include the chunk in the output document.
• echo=FALSE: Don't show code, show results.
• results='hide': Show code, don't show results.
• message=FALSE: Don't show any additional R messages.
• error=FALSE: Don't show R error messages.
• warning=FALSE: Don't show R warning messages.
• cache=TRUE: Use cached results (if available) until the code chunk is changed.
• fig.width=7, fig.height=7: Set actual figure width and height to 7 inches.
• out.width=5, out.height=5: Set output document figure width and height to 5 inches; if fig.width, fig.height are different, the output is scaled.

More chunk options can be found e.g. in the R Markdown Reference Guide and in knitr's documentation.

1. Write R code to show a barplot of how many characters participated in every Star Wars film.
2. Include the R code chunk without executing it.
3. Disable R output from an R code chunk.
4. Only show the output of an R code chunk.
5. Change the dimension of the (gg)plot.

Hint:

# R code
# Extract all films per character
df <- cbind.data.frame(film = unlist(starwars$films));
ggplot(data = df, aes(film)) + geom_bar();

Use standard \(\LaTeX\) syntax.

1. Inline equations: $x=a$ produces \(x=a\).
2. Display equations: $$ x = a $$ produces \[x=a\,.\]

Complex multi-line equation example:

 $$
 \begin{aligned}
 \frac{dq_i}{dt} &= \frac{\partial H}{\partial p_i} \\
 \frac{dp_i}{dt} &= -\frac{\partial H}{\partial q_i}
 \end{aligned}
 $$

Different ways to present tabular data.

1. Manual table creation

   First Header | Second Header
   ------------ | -------------
   Cell 1 | Cell 2
   Cell 3 | cell 4

2. knitr::kable() (all output)
3. pander::pandoc.table() (all output)
4. xtable::xtable() (only HTML and \(\LaTeX\) output)

5. stargazer::stargazer() (only HTML and \(\LaTeX\) output)

6. DT::datatable() (only HTML output, interactive)

# Load R package knitr and show table
suppressMessages(library(knitr));
kable(starwars[1:6, 1:6])

# Load R package DT and show table
suppressMessages(library(DT));
DT::datatable(starwars[, 1:10], options = list(pageLength = 6, scrollX = TRUE));

1. Manually construct a table with four columns, two rows and a header.
2. Write R code to show the first six columns of starwars in a Word document using a suitable R method.
3. Write R code to show the first 10 columns of starwars in a HTML document using a suitable R method.

Note: Depending on the R method, you might have to install additional R packages, e.g. for pander:

# R code
# Install (if necessary) and load R package 'pander'
if (!require("pander", quietly = TRUE)) {
  install.packages("pander");
  require("pander", quietly = TRUE)}

1. Insert external figures/plots (replace double with single curly brackets)

    ```{{r echo=FALSE, out.width="450px"}}
    knitr::include_graphics("path/to/figure.png")
    ```

2. base R plot (all output)
3. ggplot2 from the tidyverse (all output)

4. plotly (only HTML output)
5. dygraph (only HTML output)
6. D3.js in R (only HTML output)
   • d3heatmp
   • scatterD3
   • networkD3
   • streamgraph

df <- cbind.data.frame(skin_color = unlist(lapply(starwars$skin_color, strsplit, ", "))); 
ggplot(df, aes(skin_color)) + geom_bar() + theme_bw() + theme(axis.text.x = element_text(angle = 90, hjust = 1));

ggplotly(ggplot(starwars, aes(x = height, y = mass, label = name)) + geom_point() 
  + stat_smooth(fullrange = TRUE, method = "lm", na.rm = TRUE) + theme_bw(), height = 460, width = 960);

scatterD3(x = starwars$height, y = starwars$mass, lab = starwars$name);

1. …
2. …
3. …

Example 1: RMarkdown and shiny integration

Example 2: Bookdown